<!DOCTYPE html>
<html>
  <head>
    <meta charset='utf-8'>
    <meta content='width=device-width, initial-scale=1.0' name='viewport'>
    <meta content='' name='description'>
    <meta content='Nils Nordman' name='author'>
    <link href='/images/howl.png' rel='shortcut icon'>
    <title>Howl :: howl.Buffer</title>
    <link href="/stylesheets/bootstrap.min.css" media="screen" rel="stylesheet" type="text/css" />
    <link href="/stylesheets/syntax.css" media="screen" rel="stylesheet" type="text/css" />
    <link href="/stylesheets/howl.css" media="screen" rel="stylesheet" type="text/css" />
    <script src="https://code.jquery.com/jquery-1.12.3.min.js" type="text/javascript"></script>
    <script src="/javascripts/bootstrap.min.js" type="text/javascript"></script>
    
    <link href='//fonts.googleapis.com/css?family=Josefin+Slab' rel='stylesheet' type='text/css'>
    <link href='//fonts.googleapis.com/css?family=Open+Sans+Condensed:700' rel='stylesheet' type='text/css'>
  </head>
  <body class='doc doc_api doc_api_buffer'>
    <div class='container'>
      <div class='masthead'>
        <ul class='nav nav-pills'>
          <li>
            <a href='/'>
              <span class='glyphicon glyphicon-home'></span>
              Home
            </a>
          </li>
          <li>
            <a href='/doc/'>
              <span class='glyphicon glyphicon-book'></span>
              Documentation
            </a>
          </li>
          <li>
            <a href='/blog/'>
              <span class='glyphicon glyphicon-bullhorn'></span>
              Blog
            </a>
          </li>
          <li>
            <a href='/contact.html'>
              <span class='glyphicon glyphicon-inbox'></span>
              Contact
            </a>
          </li>
        </ul>
      </div>
      <ol class="breadcrumb"><li><a href="/">Home</a></li><li><a href='../'>Howl 0.4 Documentation</a></li><li>Api</li><li>howl.Buffer</li></ol>
      <h1 id="howl.buffer">howl.Buffer</h1>    <div class="toc">
      <div class="toc-title">
        <span>howl.Buffer</span>
      </div>
      <div class="toc-entries">
<div class="toc-group">
<a href="#overview" class="toc-group-header overview">Overview</a>
</div>
<div class="toc-group">
<a href="#properties" class="toc-group-header properties">Properties</a>
<li class=""><a href="#can_undo">can_undo</a></li>
<li class=""><a href="#collect_revisions">collect_revisions</a></li>
<li class=""><a href="#config">config</a></li>
<li class=""><a href="#data">data</a></li>
<li class=""><a href="#eol">eol</a></li>
<li class=""><a href="#file">file</a></li>
<li class=""><a href="#last_shown">last_shown</a></li>
<li class=""><a href="#length">length</a></li>
<li class=""><a href="#lines">lines</a></li>
<li class=""><a href="#mode">mode</a></li>
<li class=""><a href="#modified">modified</a></li>
<li class=""><a href="#modified_on_disk">modified_on_disk</a></li>
<li class=""><a href="#multibyte">multibyte</a></li>
<li class=""><a href="#properties">properties</a></li>
<li class=""><a href="#read_only">read_only</a></li>
<li class=""><a href="#showing">showing</a></li>
<li class=""><a href="#size">size</a></li>
<li class=""><a href="#text">text</a></li>
<li class=""><a href="#title">title</a></li>
</div>
<div class="toc-group">
<a href="#functions" class="toc-group-header functions">Functions</a>
<li class=""><a href="#buffer">Buffer</a></li>
</div>
<div class="toc-group">
<a href="#methods" class="toc-group-header methods">Methods</a>
<li class=""><a href="#append">append</a></li>
<li class=""><a href="#as_one_undo">as_one_undo</a></li>
<li class=""><a href="#byte_offset">byte_offset</a></li>
<li class=""><a href="#char_offset">char_offset</a></li>
<li class=""><a href="#chunk">chunk</a></li>
<li class=""><a href="#context_at">context_at</a></li>
<li class=""><a href="#delete">delete</a></li>
<li class=""><a href="#find">find</a></li>
<li class=""><a href="#insert">insert</a></li>
<li class=""><a href="#lex">lex</a></li>
<li class=""><a href="#redo">redo</a></li>
<li class=""><a href="#reload">reload </a></li>
<li class=""><a href="#replace">replace</a></li>
<li class=""><a href="#rfind">rfind</a></li>
<li class=""><a href="#save">save</a></li>
<li class=""><a href="#save_as">save_as </a></li>
<li class=""><a href="#sub">sub</a></li>
<li class=""><a href="#undo">undo</a></li>
</div>
</div>
</div>
&#x000A;&#x000A;<h2 id="overview">Overview</h2>&#x000A;&#x000A;<p>Buffers are in-memory containers of text. While they are often associated with a&#x000A;specific file on disk, this need not be the case. Instead they simply represent&#x000A;some textual content loaded into memory, available for manipulation within Howl.&#x000A;Buffer manipulation is typically done in one of two ways; it can be done as a&#x000A;result of a user interacting with an <a href="ui/editor.html">Editor</a> displaying a particular buffer, or&#x000A;it can be done programmatically by manipulating the buffer directly.</p>&#x000A;&#x000A;<p>Buffers can be created directly and used without being associated with a file or&#x000A;an <a href="ui/editor.html">Editor</a>, or without showing up in the buffer list. But if you want the&#x000A;buffer to show up in the buffer list you need to either create it through, or&#x000A;register it with, <a href="application.html">Application</a>.</p>&#x000A;&#x000A;<p><em>See also</em>:</p>&#x000A;&#x000A;<ul>&#x000A;<li>The <a href="../spec/buffer_spec.html">spec</a> for Buffer</li>&#x000A;<li><a href="application.html#new_buffer">Application.new_buffer</a></li>&#x000A;<li><a href="application.html#add_buffer">Application.add_buffer</a></li>&#x000A;</ul>&#x000A;&#x000A;<h2 id="properties">Properties</h2>&#x000A;&#x000A;<h3 id="can_undo">can_undo</h3>&#x000A;&#x000A;<p>Whether the buffer contains any undo information that can be undo via the&#x000A;<a href="#undo">undo</a> method. You can assign false to clear any undo information&#x000A;currently available for a particular buffer.</p>&#x000A;<pre class="highlight lua"><span class="kd">local</span> <span class="n">buffer</span> <span class="o">=</span> <span class="n">Buffer</span><span class="p">()</span>&#x000A;<span class="n">buffer</span><span class="p">.</span><span class="n">text</span> <span class="o">=</span> <span class="s1">'my buffer text!'</span>&#x000A;<span class="nb">print</span><span class="p">(</span><span class="n">buffer</span><span class="p">.</span><span class="n">can_undo</span><span class="p">)</span>&#x000A;<span class="c1">-- =&gt; true</span>&#x000A;<span class="n">buffer</span><span class="p">.</span><span class="n">can_undo</span> <span class="o">=</span> <span class="kc">false</span>&#x000A;<span class="nb">print</span><span class="p">(</span><span class="n">buffer</span><span class="p">.</span><span class="n">can_undo</span><span class="p">)</span>&#x000A;<span class="c1">-- =&gt; false</span>&#x000A;</pre>&#x000A;<h3 id="collect_revisions">collect_revisions</h3>&#x000A;&#x000A;<p>Whether modifying operations should collect undo revisions. Defaults to true.</p>&#x000A;&#x000A;<h3 id="config">config</h3>&#x000A;&#x000A;<p>A configuration object that can be used to access and manipulate <a href="config.html">config</a>&#x000A;variables for a certain buffer. This object is automatically chained to the&#x000A;buffer&rsquo;s mode&rsquo;s config property, meaning it will defer to what is set for the&#x000A;mode (and in extension set globally) should a particular configuration variable&#x000A;not be set specifically for the buffer.</p>&#x000A;&#x000A;<h3 id="data">data</h3>&#x000A;&#x000A;<p>A general-purpose table that can be used for storing arbitrary information about&#x000A;a particular buffer. Intended as a way for any Howl code to have a place to&#x000A;assign data with a buffer. Similar to <a href="#properties">properties</a> but ephemeral,&#x000A;i.e. any data in this table will be lost upon a restart. As this is shared by&#x000A;all Howl code, take care to namespace any specific data properly.</p>&#x000A;&#x000A;<h3 id="eol">eol</h3>&#x000A;&#x000A;<p>The line ending currently in effect for the buffer. One of:</p>&#x000A;&#x000A;<ul>&#x000A;<li><code>&#39;\n&#39;</code></li>&#x000A;<li><code>&#39;\r\n&#39;</code></li>&#x000A;<li><code>&#39;\r&#39;</code></li>&#x000A;</ul>&#x000A;&#x000A;<h3 id="file">file</h3>&#x000A;&#x000A;<p>An optional file associated with the current buffer. Assigning to this causes&#x000A;the buffer to be associated with assigned file, and loaded with the file&rsquo;s&#x000A;contents. If the file does not exist, the buffer&rsquo;s current contents will be&#x000A;emptied. The buffer&rsquo;s <a href="#title">title</a> is automatically updated from the file&rsquo;s&#x000A;name as part of the assignment.</p>&#x000A;&#x000A;<h3 id="last_shown">last_shown</h3>&#x000A;&#x000A;<p>A timestamp value, as obtained from Lua&rsquo;s <code>os.time</code>, specifying when the buffer&#x000A;was last <a href="#showing">showing</a>.</p>&#x000A;&#x000A;<h3 id="length">length</h3>&#x000A;&#x000A;<p>The length of the buffer&rsquo;s text, in code points.</p>&#x000A;&#x000A;<h3 id="lines">lines</h3>&#x000A;&#x000A;<p>An instance of <a href="lines.html">Lines</a> for the buffer that allows for line based access to the&#x000A;content.</p>&#x000A;&#x000A;<h3 id="mode">mode</h3>&#x000A;&#x000A;<p>The buffer&rsquo;s <a href="mode.html">mode</a>. When assigning to this:</p>&#x000A;&#x000A;<ul>&#x000A;<li>the <code>buffer-mode-set</code> signal is emitted.</li>&#x000A;<li>any previously lexed content is re-lexed using the new mode&rsquo;s lexer, if any</li>&#x000A;</ul>&#x000A;&#x000A;<h3 id="modified">modified</h3>&#x000A;&#x000A;<p>A boolean indicating whether the buffer is modified or not. You can explicitly&#x000A;assign to this to force a particular status.</p>&#x000A;&#x000A;<h3 id="modified_on_disk">modified_on_disk</h3>&#x000A;&#x000A;<p>For a buffer with an associated file, this is a boolean indicating whether the&#x000A;file has changed since its contents was loaded into the buffer. Always false for&#x000A;a buffer without an associated file.</p>&#x000A;&#x000A;<h3 id="multibyte">multibyte</h3>&#x000A;&#x000A;<p>A boolean indicating whether the buffer&rsquo;s text contains multibyte characters.</p>&#x000A;&#x000A;<h3 id="properties">properties</h3>&#x000A;&#x000A;<p>A general-purpose table that can be used for storing arbitrary information about&#x000A;a particular buffer. Intended as a way for any Howl code to have a place where&#x000A;to store persistent information for a buffer. The contents of this is&#x000A;automatically serialized and restored with the session. As this is shared by all&#x000A;Howl code, take care to namespace any specific data properly.</p>&#x000A;&#x000A;<h3 id="read_only">read_only</h3>&#x000A;&#x000A;<p>A boolean specifying whether the buffer is read-only or not. A read-only buffer&#x000A;can not be modified. Assign to this to control the status.</p>&#x000A;&#x000A;<h3 id="showing">showing</h3>&#x000A;&#x000A;<p>A boolean indicating whether the buffer is currently showing in any editor.</p>&#x000A;&#x000A;<h3 id="size">size</h3>&#x000A;&#x000A;<p>The size of the buffer&rsquo;s text, in bytes.</p>&#x000A;&#x000A;<h3 id="text">text</h3>&#x000A;&#x000A;<p>The buffer&rsquo;s text. Assigning to this causes the entire buffer contents to be&#x000A;replaced with the assigned text.</p>&#x000A;&#x000A;<h3 id="title">title</h3>&#x000A;&#x000A;<p>The buffer&rsquo;s title. This is automatically set whenever assigning a <a href="#file">file</a>&#x000A;to a buffer, but can be explicitly specified as well. Assigning to this causes&#x000A;the <code>buffer-title-set</code> signal to be emitted.</p>&#x000A;&#x000A;<h2 id="functions">Functions</h2>&#x000A;&#x000A;<h3 id="buffer">Buffer<span class="arg-list">(mode = {})</span></h3>&#x000A;&#x000A;<p>Creates a new buffer, optionally specifying its mode.</p>&#x000A;&#x000A;<h2 id="methods">Methods</h2>&#x000A;&#x000A;<h3 id="append">append<span class="arg-list">(text)</span></h3>&#x000A;&#x000A;<p>Appends <code>text</code> to the end of the buffer&rsquo;s current text.</p>&#x000A;&#x000A;<h3 id="as_one_undo">as_one_undo<span class="arg-list">(f)</span></h3>&#x000A;&#x000A;<p>Invokes the function <code>f</code>, and collects any modifications performed within <code>f</code> as&#x000A;one undo group. Calling this, and subsequently calling <a href="#undo">undo</a> will thus&#x000A;undo all modifications made within <code>f</code>.</p>&#x000A;&#x000A;<h3 id="byte_offset">byte_offset<span class="arg-list">(char_offset)</span></h3>&#x000A;&#x000A;<p>Returns the byte offset corresponding to the passed <code>char_offset</code>. Raises an&#x000A;error if <code>char_offset</code> is out of bounds.</p>&#x000A;&#x000A;<h3 id="char_offset">char_offset<span class="arg-list">(byte_offset)</span></h3>&#x000A;&#x000A;<p>Returns the character offset corresponding to the passed <code>byte_offset</code>. Raises&#x000A;an error if <code>byte_offset</code> is out of bounds.</p>&#x000A;&#x000A;<h3 id="chunk">chunk<span class="arg-list">(start_pos, end_pos)</span></h3>&#x000A;&#x000A;<p>Returns a <a href="chunk.html">Chunk</a> for the given range.</p>&#x000A;&#x000A;<h3 id="context_at">context_at<span class="arg-list">(pos)</span></h3>&#x000A;&#x000A;<p>Returns a <a href="context.html">Context</a> for the specified position.</p>&#x000A;&#x000A;<h3 id="delete">delete<span class="arg-list">(start_pos, end_pos)</span></h3>&#x000A;&#x000A;<p>Deletes the text between <code>start_pos</code> and <code>end_pos</code>, which specify an inclusive&#x000A;range.</p>&#x000A;&#x000A;<h3 id="find">find<span class="arg-list">(search, init = 1)</span></h3>&#x000A;&#x000A;<p>Searches for the text <code>search</code> in the the buffer&rsquo;s text starting at character&#x000A;position <code>init</code>. Returns character offsets <code>start_pos</code>, <code>end_pos</code> of the first&#x000A;match, or <code>nil</code> if no match was found. A negative <code>init</code> specifies an offset&#x000A;from the end, where -1 means the last character of the buffer.</p>&#x000A;&#x000A;<p>See also: <a href="#rfind">rfind()</a></p>&#x000A;&#x000A;<h3 id="insert">insert<span class="arg-list">(text, pos)</span></h3>&#x000A;&#x000A;<p>Inserts <code>text</code> at the position given by <code>pos</code>, and returns the position right&#x000A;after newly inserted text. examples.</p>&#x000A;&#x000A;<h3 id="lex">lex<span class="arg-list">(end_pos)</span></h3>&#x000A;&#x000A;<p>Lexes the buffer content using the <a href="#mode">mode</a>s lexer, if available. The&#x000A;content is lexed up until <code>end_pos</code>, or until the end of the buffer if omitted.</p>&#x000A;&#x000A;<h3 id="redo">redo<span class="arg-list">()</span></h3>&#x000A;&#x000A;<p>Redo the last, previously <a href="#undo">undo</a>ne, buffer modification.</p>&#x000A;&#x000A;<h3 id="reload">reload <span class="arg-list">(force = false)</span></h3>&#x000A;&#x000A;<p>Reloads the buffer contents from its associated <a href="#file">file</a>. Raises an error&#x000A;if the buffer does not have any associated file. Emits the <code>buffer-reloaded</code>&#x000A;signal. Returns <code>true</code> if the buffer was successfully loaded and <code>false</code>&#x000A;otherwise. A modified buffer will not be reloaded (with <code>false</code> being returned),&#x000A;unless <code>force</code> is true.</p>&#x000A;&#x000A;<h3 id="replace">replace<span class="arg-list">(pattern, replacement)</span></h3>&#x000A;&#x000A;<p>Replaces all occurrences of <code>pattern</code> with <code>replacement</code>, and returns the number&#x000A;of replacements made. <code>pattern</code> can be either a Lua pattern, or a <a href="regex.html">regular&#x000A;expression</a>.</p>&#x000A;&#x000A;<h3 id="rfind">rfind<span class="arg-list">(search, init = @length)</span></h3>&#x000A;&#x000A;<p>Reverse search: searches backwards for the text <code>search</code> in the buffer&rsquo;s text&#x000A;starting at the character position <code>init</code>. Returns character offsets&#x000A;<code>start_pos</code>, <code>end_pos</code> of the first match, or <code>nil</code> if no match was found. A&#x000A;negative <code>init</code> specifies an offset from the end, where -1 means the last&#x000A;character of the buffer. The rightmost character of the match found may be at&#x000A;the <code>init</code> position, however, no part of the match will be to the right of&#x000A;<code>init</code>.</p>&#x000A;&#x000A;<p>See also: <a href="#find">find()</a></p>&#x000A;&#x000A;<h3 id="save">save<span class="arg-list">()</span></h3>&#x000A;&#x000A;<p>Saves the buffer&rsquo;s content to its associated file, if any. Emits the&#x000A;<code>buffer-saved</code> signal. As part of saving the content, optionally removes any&#x000A;trailing white-space and ensures that there&rsquo;s an eol at the end of the file,&#x000A;according to the <code>strip_trailing_whitespace</code> and <code>ensure_newline_at_eof</code>&#x000A;configuration variables.</p>&#x000A;&#x000A;<h3 id="save_as">save_as <span class="arg-list">(file)</span></h3>&#x000A;&#x000A;<p>Associates the buffer with, and saves the buffer&rsquo;s content to <code>file</code>. The save&#x000A;is performed using the same semantics as for <a href="#save">save()</a>.</p>&#x000A;&#x000A;<h3 id="sub">sub<span class="arg-list">(start_pos, end_pos)</span></h3>&#x000A;&#x000A;<p>Returns the text from character offset <code>start_pos</code> to <code>end_pos</code> (both&#x000A;inclusive). Returns an empty string when <code>start_pos</code> is larger than <code>end_pos</code>.&#x000A;Negative offsets count from end of the buffer.</p>&#x000A;<pre class="highlight lua"><span class="kd">local</span> <span class="n">buffer</span> <span class="o">=</span> <span class="n">Buffer</span><span class="p">(</span><span class="s1">'abcde'</span><span class="p">)</span>&#x000A;<span class="nb">print</span><span class="p">(</span><span class="n">buffer</span><span class="err">\</span><span class="n">sub</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">))</span>&#x000A;<span class="c1">-- =&gt; 'ab'</span>&#x000A;<span class="nb">print</span><span class="p">(</span><span class="n">buffer</span><span class="err">\</span><span class="n">sub</span><span class="p">(</span><span class="o">-</span><span class="mi">2</span><span class="p">,</span> <span class="o">-</span><span class="mi">1</span><span class="p">))</span>&#x000A;<span class="c1">-- =&gt; 'de'</span>&#x000A;</pre>&#x000A;<h3 id="undo">undo<span class="arg-list">()</span></h3>&#x000A;&#x000A;<p>Undo the last buffer modification.</p>
      <div class='footer text-muted'>
        <a href='/'>
          <img width="50" height="50" class="footer-logo" src="/images/howl.png" />
        </a>
        <div class='footer-follow'>
          <p>
            <a class='twitter-follow-button' data-lang='en' data-show-count='false' href='https://twitter.com/howleditor' rel='me'>
              Follow @howleditor
            </a>
          </p>
          <p>
            <a class='twitter-share-button' data-count='none' data-hashtags='howleditor' data-lang='en' data-text='The Howl Editor, a general purpose, light-weight customizable editor.' data-url='http://howl.io' href='https://twitter.com/share'>
              Tweet
            </a>
          </p>
        </div>
        <div class='footer-blurb'>
          <div>The Howl editor.</div>
          <div>
            Copyright 2012-2016
            <a class='alert-link' href='https://github.com/howl-editor/howl/contributors'>
              The Howl Developers.
            </a>
          </div>
        </div>
      </div>
    </div>
    <script>
      <!-- / GA -->
      (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
      (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
      m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
      })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
      ga('create', 'UA-45283282-1', 'howl.io');
      ga('send', 'pageview');
      <!-- / Twitter -->
      !function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0];
      if(!d.getElementById(id)){js=d.createElement(s);js.id=id;
      js.src="//platform.twitter.com/widgets.js";
      fjs.parentNode.insertBefore(js,fjs);}}(document,"script","twitter-wjs");
    </script>
  </body>
</html>
